
package com.studiofortress.sf.structure;

import com.studiofortress.sf.graphics.GraphicsGL;
import com.studiofortress.sf.graphics.display.Controls;

/**
 * This is an extension on the original Controls interface that adds support for
 * mouse location in relation to an associated world. The extra methods take
 * into account the location of the associated World.
 *
 * getWorld must return the World that the method getWorldMouseX,
 * getWorldMouseY and setWorldMousePosition work in relation with.
 *
 * getWorldMouseX and getWorldMouseY may return values larger then the World's
 * size if the mouse is outside of the World.
 * 
 * This interface makes no guarantees that the World returned by getWorld is
 * being painted to the screen and can be seen.
 *
 * @author Joseph Lenton
 */
public interface WorldControls<A extends Actor<? extends GraphicsGL>> extends Controls
{
    /**
     * @return The World object this WorldControls is for.
     */
    public abstract World getWorld();

    /**
     * @return The location of the mouse along the x-axis inside the world at getWorld().
     */
    public abstract int getWorldMouseX();

    /**
     * This takes into account the position of the associated world within this
     * WorldControls.
     * @return The location of the mouse inside of this world.
     */
    public abstract int getWorldMouseY();

    /**
     * Checks if the current mouse position in the world is on top of the Actor
     * given. Uses the Actors location, width and height to calculate this.
     *
     * @param actor The Actor to check against the mouses location.
     * @return True if the mouse is on top of the Actor, otherwise false.
     */
    public abstract boolean isActorUnderMouse( A actor );

    /**
     * Checks if the curremt position of the mouse in the World this controls
     * comes from is within the given Actor's bounds. The result is returned.
     * @param actor The Actor to check, cannot be null.
     * @param mouseButton The button to check for. i.e. Controls.LEFT_MOUSE or Controls.RIGHT_MOUSE.
     * @return True if the mouse pointer is currently over the actor given, otherwise false.
     */
    public abstract boolean isActorClicked( A actor, int mouseButton );
}
